Skip to content

docs: integrate npm package documentation#148

Merged
omsherikar merged 1 commit intomainfrom
docs/integrate-npm-docs
Apr 4, 2026
Merged

docs: integrate npm package documentation#148
omsherikar merged 1 commit intomainfrom
docs/integrate-npm-docs

Conversation

@omsherikar
Copy link
Copy Markdown
Contributor

@omsherikar omsherikar commented Apr 4, 2026

Summary by CodeRabbit

  • Documentation
    • Launched comprehensive npm package documentation site with API reference, CLI command guides, and core concepts
    • Added configuration guide for refactron.yaml with analyzer settings, verification timeouts, and output controls
    • Documented verification engine, blast radius calculation, work sessions, and temporal analysis
    • Included language-specific guides for Python and TypeScript adapters and quickstart tutorial

Copilot AI review requested due to automatic review settings April 4, 2026 20:19
@mintlify
Copy link
Copy Markdown

mintlify bot commented Apr 4, 2026

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
refactron 🟢 Ready View Preview Apr 4, 2026, 8:19 PM

@github-actions github-actions bot added documentation Improvements or additions to documentation size: x-large labels Apr 4, 2026
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 4, 2026

📝 Walkthrough

Walkthrough

This PR introduces comprehensive documentation for the npm package, covering API reference (adapters, models, orchestrator), CLI commands, core concepts, language guides, configuration, and getting-started materials, while restructuring the documentation navigation to accommodate both Python and Node package documentation.

Changes

Cohort / File(s) Summary
API Reference
docs/docs-npm/api/overview.mdx, docs/docs-npm/api/adapters.mdx, docs/docs-npm/api/models.mdx, docs/docs-npm/api/orchestrator.mdx
Defines core API surfaces: package entry points and exports, ILanguageAdapter interface contract and lifecycle methods, public model types (CodeIssue, BlastRadius, etc.), and Orchestrator class methods and control flow.
CLI Commands
docs/docs-npm/cli/overview.mdx, docs/docs-npm/cli/analyze.mdx, docs/docs-npm/cli/autofix.mdx, docs/docs-npm/cli/verify.mdx, docs/docs-npm/cli/issue-browser.mdx, docs/docs-npm/cli/session.mdx, docs/docs-npm/cli/other-commands.mdx
Documents CLI entry points, command syntax, behavioral workflows, and TUI navigation for analyze, autofix, verify, issue browsing, session management, and utility commands.
Core Concepts
docs/docs-npm/concepts/blast-radius.mdx, docs/docs-npm/concepts/verification.mdx, docs/docs-npm/concepts/temporal-analysis.mdx, docs/docs-npm/concepts/sessions.mdx
Explains key architectural patterns: blast radius computation and scoring, verification gates and check selection, temporal analysis from git history, and work session lifecycle/persistence.
Language Adapters
docs/docs-npm/languages/python.mdx, docs/docs-npm/languages/typescript.mdx
Describes adapter selection criteria, analysis/fix pipelines, verification steps, and runtime requirements for Python and TypeScript projects.
Getting Started & Configuration
docs/docs-npm/introduction.mdx, docs/docs-npm/quickstart.mdx, docs/docs-npm/configuration.mdx
Provides product overview, step-by-step quickstart with example workflows and OAuth setup, and comprehensive refactron.yaml configuration reference with per-analyzer settings.
Site Navigation & Structure
docs/docs-npm/mint.json, docs/docs.json
Adds Mintlify site configuration (theme, topbar, navigation) for npm docs and restructures docs.json to support tabbed navigation separating Python and Node package documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Suggested labels

documentation, size: medium

Poem

📚 Through docs the rabbit hops with glee,
From adapters down to symphony—
Each guide and page, a nibbled treat,
APIs, CLI, complete and neat! 🐰✨
Now builders know just where to run,
Your npm docs are finally done!

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title directly describes the main change: adding npm package documentation to the repository.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/integrate-npm-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Integrates a new Mintlify documentation set for the npm (Node) package alongside the existing Python package docs by restructuring site navigation into tabs and adding a full set of Node-focused concept/CLI/API pages.

Changes:

  • Updated docs/docs.json navigation to use tabbed docs (“Python Package” / “Node Package”).
  • Added a complete docs/docs-npm/ documentation tree (intro, quickstart, configuration, concepts, CLI pages, languages, API reference).
  • Added a Mintlify config file for the npm docs subtree (docs/docs-npm/mint.json).

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
docs/docs.json Adds tabbed navigation and wires in the new docs-npm/* pages under a “Node Package” tab.
docs/docs-npm/mint.json Mintlify config for the npm docs subtree (branding/nav/external links).
docs/docs-npm/introduction.mdx Node package introduction/positioning and core differentiators.
docs/docs-npm/quickstart.mdx Node package install + first-run + REPL workflow walkthrough.
docs/docs-npm/configuration.mdx Node package configuration reference and examples.
docs/docs-npm/concepts/blast-radius.mdx Explains blast radius model and how it affects verification strictness.
docs/docs-npm/concepts/verification.mdx Documents the verification engine checks, selection, and timeouts.
docs/docs-npm/concepts/sessions.mdx Describes persisted work sessions and their lifecycle.
docs/docs-npm/concepts/temporal-analysis.mdx Documents git-history-based enrichment and risk labeling.
docs/docs-npm/cli/overview.mdx CLI entry points, auth, detection, and command map.
docs/docs-npm/cli/analyze.mdx analyze command behavior and session creation.
docs/docs-npm/cli/issue-browser.mdx Interactive TUI issue browser usage and keybindings.
docs/docs-npm/cli/autofix.mdx autofix command behavior and flags.
docs/docs-npm/cli/verify.mdx verify command behavior and what checks run.
docs/docs-npm/cli/session.mdx session listing/loading behavior.
docs/docs-npm/cli/other-commands.mdx Auth/status/diff/rollback/issues/help/exit documentation.
docs/docs-npm/languages/python.mdx Python adapter behavior (detection, analysis, verification).
docs/docs-npm/languages/typescript.mdx TypeScript adapter behavior and current limitations.
docs/docs-npm/api/overview.mdx High-level API layering and stability notes.
docs/docs-npm/api/models.mdx Documents core types used by the Node package.
docs/docs-npm/api/adapters.mdx Documents ILanguageAdapter interface and responsibilities.
docs/docs-npm/api/orchestrator.mdx Documents orchestrator responsibilities and methods.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +3 to +12
description: Customize Refactron with a refactron.yaml file in your project root.
---

## Config File

Create `refactron.yaml` in your project root. All fields are optional — Refactron ships with sensible defaults and deep-merges your overrides.

```yaml
# refactron.yaml
version: 1
Copy link

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The CLI in this repository uses .refactron.yaml (not refactron.yaml) and expects version to be "1.0" (ConfigValidator.CURRENT_VERSION). Consider updating the filename/version in this page (or explicitly calling out that the Node Package uses a different config filename/schema) to avoid users creating a config that the shipped CLI won’t load/validate.

Suggested change
description: Customize Refactron with a refactron.yaml file in your project root.
---
## Config File
Create `refactron.yaml` in your project root. All fields are optional — Refactron ships with sensible defaults and deep-merges your overrides.
```yaml
# refactron.yaml
version: 1
description: Customize Refactron with a .refactron.yaml file in your project root.
---
## Config File
Create `.refactron.yaml` in your project root. All fields are optional — Refactron ships with sensible defaults and deep-merges your overrides.
```yaml
# .refactron.yaml
version: "1.0"

Copilot uses AI. Check for mistakes.
Comment on lines +22 to +34
code_smell:
enabled: true
max_method_lines: 50 # lines per function/method limit

dead_code:
enabled: true

type_hints:
enabled: true

dependencies:
enabled: true

Copy link

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This config example uses analyzer keys like code_smell and dependencies, but the analyzer names accepted by this repo’s config validator are code_smells and dependency (see ConfigValidator.VALID_ANALYZERS). If this page is meant to document the Python package in this repo, these keys should be updated so copied configs validate correctly; if it’s meant for a separate npm CLI, please call that out explicitly to prevent users mixing schemas.

Copilot uses AI. Check for mistakes.

## Stability

Types under `src/core/models.ts` and `src/adapters/interface.ts` are marked **LOCKED** in-repo: treat them as semver-sensitive when depending on them from outside the project.
Copy link

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page points to src/core/models.ts and src/adapters/interface.ts as in-repo sources, but this repository doesn’t contain a src/ tree. If the intent is to reference the separate TypeScript/npm repo, consider linking to the exact GitHub path/commit there (or rewording to avoid implying these files exist in this repo).

Suggested change
Types under `src/core/models.ts` and `src/adapters/interface.ts` are marked **LOCKED** in-repo: treat them as semver-sensitive when depending on them from outside the project.
The Models and Adapters API surfaces documented here are treated as **LOCKED**: if you depend on them from outside the project, treat them as semver-sensitive.

Copilot uses AI. Check for mistakes.

## Interface

Language adapters implement `ILanguageAdapter` (`src/adapters/interface.ts`):
Copy link

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The interface reference src/adapters/interface.ts does not exist in this repository. If these docs are meant to describe the npm/TypeScript codebase hosted elsewhere, link to that repo/path (or rephrase to avoid a broken “Source” reference for readers browsing this repo).

Suggested change
Language adapters implement `ILanguageAdapter` (`src/adapters/interface.ts`):
Language adapters implement the following `ILanguageAdapter` contract:

Copilot uses AI. Check for mistakes.

## Source

`src/core/orchestrator.ts`
Copy link

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The “Source” reference src/core/orchestrator.ts doesn’t exist in this repository. Please link to the correct source location (e.g., in the external TypeScript/npm repo) or adjust wording so it’s not a dead reference for readers.

Suggested change
`src/core/orchestrator.ts`
This API is implemented in the project's TypeScript/npm source package. Refer to that package's repository for the current `Orchestrator` implementation.

Copilot uses AI. Check for mistakes.
Comment on lines +104 to +110
The orchestrator uses `PipelineSession`, `FixQueueItem`, `FixStatus`, and related types for fix application and blocking. See `src/core/models.ts` for full definitions.

---

## Source

Definitions live in `src/core/models.ts` in the repository.
Copy link

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page says definitions live in src/core/models.ts, but that path doesn’t exist in this repository. If this is meant to refer to the external TypeScript/npm implementation, consider linking to the actual file in that repo (or remove the “Source” pointer).

Suggested change
The orchestrator uses `PipelineSession`, `FixQueueItem`, `FixStatus`, and related types for fix application and blocking. See `src/core/models.ts` for full definitions.
---
## Source
Definitions live in `src/core/models.ts` in the repository.
The orchestrator uses `PipelineSession`, `FixQueueItem`, `FixStatus`, and related types for fix application and blocking. These additional types are part of the TypeScript/npm implementation, but the `src/core/models.ts` path referenced previously is not present in this repository.
---
## Source
This page documents the public model shapes shown above. The previously referenced `src/core/models.ts` path is not present in this repository.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

🧹 Nitpick comments (3)
docs/docs-npm/api/overview.mdx (1)

8-11: Prefer documenting exported entrypoints over dist/* paths.

Suggest emphasizing package.json exports as the primary import surface and de-emphasizing deep dist/... imports, which are more likely to break across releases.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/docs-npm/api/overview.mdx` around lines 8 - 11, Update the docs text to
recommend importing from the package's published entry points (the package.json
"exports") instead of deep `dist/...` paths: replace or reword the sentence that
references `dist/cli/index.js` and examples like `dist/core/models.js` /
`dist/core/orchestrator.js` to stress using the exported entrypoints (e.g.,
top-level package imports or named exports defined in package.json) as the
supported public API for the `refactron` CLI and library; keep a short note that
deep `dist/*` imports may break across releases and point readers to check
package.json "exports" for valid import paths.
docs/docs-npm/cli/verify.mdx (1)

8-14: Make the usage synopsis explicit for session-wide mode.

Line 9 currently shows verify [file], but Line 13 also documents . and no-arg behavior. Consider reflecting that directly in the usage line to reduce ambiguity.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/docs-npm/cli/verify.mdx` around lines 8 - 14, Update the CLI usage
synopsis so it explicitly shows session-wide mode in the code block that
currently reads "verify [file]"; change it to include "." and the no-arg form
(for example "verify [file|.]" or a two-line snippet like "verify [file]" and
"verify" / "verify .") so the usage aligns with the explanatory text about "."
and no-arg behavior in the same section.
docs/docs-npm/quickstart.mdx (1)

30-30: Avoid hardcoding a specific CLI version in Quickstart output.

Line 30 uses a pinned example (0.1.0-beta.2), which will go stale quickly. Prefer a placeholder-style output example.

Suggested doc tweak
 refactron --version
-# 0.1.0-beta.2
+# x.y.z
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/docs-npm/quickstart.mdx` at line 30, Replace the hardcoded header "#
0.1.0-beta.2" in the quickstart output example with a placeholder-style value so
the docs don't go stale; e.g., change the string "0.1.0-beta.2" (found in the
header line "# 0.1.0-beta.2") to a generic placeholder such as "<cli-version>"
or "{{cli_version}}" and update any adjacent explanatory text to refer to the
placeholder.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/docs-npm/api/models.mdx`:
- Around line 104-110: The docs reference the non-existent TypeScript file
src/core/models.ts; update the link and text to point to the actual Python
source refactron/core/models.py (or explicitly state this doc targets a separate
JS/TS package if that was intended) and ensure the types mentioned
(PipelineSession, FixQueueItem, FixStatus) are referenced to their Python
definitions or a note is added clarifying language mismatch.

In `@docs/docs-npm/cli/analyze.mdx`:
- Around line 40-42: The "Supported language detected" link currently points
only to /docs-npm/languages/python which is too narrow; update the link target
in the docs text "Supported language detected for the project. See
[Languages](/docs-npm/languages/python)." to point to a neutral languages index
(e.g., /docs-npm/languages) or include links to both relevant pages (e.g.,
Python and TypeScript) so Node users aren't misrouted; edit the link target text
in docs/docs-npm/cli/analyze.mdx accordingly.

In `@docs/docs-npm/cli/issue-browser.mdx`:
- Around line 28-39: The docs table for the issue browser is missing the
severity drill-in and navigation keybindings used by the interactive viewer;
update the CLI docs page (issue-browser.mdx) to include the keys `1`-`4` for
drilling into severity groups and `n`/`p`/`b`/`q` for next/previous/back/quit
navigation, and add a short note that `refactron analyze` launches the TTY
interactive issue viewer with severity-grouped navigation and falls back to
non-interactive output for CI/CD; reference the interactive issue
viewer/keybinding descriptions in the same table and adjacent paragraph so
readers see the mapping next to existing entries like `↑`/`↓`, `d`, `a`, `A`,
`v`, `/`, `g`/`G`, and `q`.

In `@docs/docs-npm/concepts/verification.mdx`:
- Around line 8-9: The doc incorrectly states checks are selected by blast
radius; update the "Verification Engine" documentation to state that
VerificationEngine always initializes and runs all three checks (syntax, medium,
test gate) sequentially, short-circuiting on the first failure, rather than
skipping checks by blast level; specifically replace any wording that says
checks are chosen by blast radius or that the test gate runs only for
high/critical with a clear description of the current implementation
(VerificationEngine initializes all checks and executes them in order), and
optionally add a note that blast-level-based skipping is a planned/possible
enhancement if desired.

In `@docs/docs-npm/configuration.mdx`:
- Around line 8-49: The docs show nested config sections (analyzers.*,
verification.*, autofix.*, output.*) but the loader expects flat fields passed
into RefactronConfig via RefactronConfig.from_file (refactron/core/config.py),
causing TypeError/ConfigError; fix by updating this example YAML to the flat
top-level shape that RefactronConfig expects (use the exact field names from the
RefactronConfig dataclass) or alternatively modify RefactronConfig.from_file to
deep-merge and normalize nested sections into the flat dict before calling
cls(**config_dict); reference RefactronConfig and from_file to locate the code
to change.

In `@docs/docs-npm/quickstart.mdx`:
- Line 9: Update the prerequisite sentence in quickstart.mdx to stop claiming
Git enables "blast radius": edit the line that currently reads "**Git**
(optional but recommended — enables temporal analysis and blast radius)" to
remove "and blast radius" so it only states that Git enables temporal analysis;
keep the rest of the phrasing intact to avoid conflicting guidance about
structural (blast radius) analysis being separate.

---

Nitpick comments:
In `@docs/docs-npm/api/overview.mdx`:
- Around line 8-11: Update the docs text to recommend importing from the
package's published entry points (the package.json "exports") instead of deep
`dist/...` paths: replace or reword the sentence that references
`dist/cli/index.js` and examples like `dist/core/models.js` /
`dist/core/orchestrator.js` to stress using the exported entrypoints (e.g.,
top-level package imports or named exports defined in package.json) as the
supported public API for the `refactron` CLI and library; keep a short note that
deep `dist/*` imports may break across releases and point readers to check
package.json "exports" for valid import paths.

In `@docs/docs-npm/cli/verify.mdx`:
- Around line 8-14: Update the CLI usage synopsis so it explicitly shows
session-wide mode in the code block that currently reads "verify [file]"; change
it to include "." and the no-arg form (for example "verify [file|.]" or a
two-line snippet like "verify [file]" and "verify" / "verify .") so the usage
aligns with the explanatory text about "." and no-arg behavior in the same
section.

In `@docs/docs-npm/quickstart.mdx`:
- Line 30: Replace the hardcoded header "# 0.1.0-beta.2" in the quickstart
output example with a placeholder-style value so the docs don't go stale; e.g.,
change the string "0.1.0-beta.2" (found in the header line "# 0.1.0-beta.2") to
a generic placeholder such as "<cli-version>" or "{{cli_version}}" and update
any adjacent explanatory text to refer to the placeholder.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a0f252e4-9283-42b7-a8fa-2b44844d5d4a

📥 Commits

Reviewing files that changed from the base of the PR and between 049fb7b and 1ee5f50.

📒 Files selected for processing (22)
  • docs/docs-npm/api/adapters.mdx
  • docs/docs-npm/api/models.mdx
  • docs/docs-npm/api/orchestrator.mdx
  • docs/docs-npm/api/overview.mdx
  • docs/docs-npm/cli/analyze.mdx
  • docs/docs-npm/cli/autofix.mdx
  • docs/docs-npm/cli/issue-browser.mdx
  • docs/docs-npm/cli/other-commands.mdx
  • docs/docs-npm/cli/overview.mdx
  • docs/docs-npm/cli/session.mdx
  • docs/docs-npm/cli/verify.mdx
  • docs/docs-npm/concepts/blast-radius.mdx
  • docs/docs-npm/concepts/sessions.mdx
  • docs/docs-npm/concepts/temporal-analysis.mdx
  • docs/docs-npm/concepts/verification.mdx
  • docs/docs-npm/configuration.mdx
  • docs/docs-npm/introduction.mdx
  • docs/docs-npm/languages/python.mdx
  • docs/docs-npm/languages/typescript.mdx
  • docs/docs-npm/mint.json
  • docs/docs-npm/quickstart.mdx
  • docs/docs.json

Comment on lines +104 to +110
The orchestrator uses `PipelineSession`, `FixQueueItem`, `FixStatus`, and related types for fix application and blocking. See `src/core/models.ts` for full definitions.

---

## Source

Definitions live in `src/core/models.ts` in the repository.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Checking for referenced TypeScript models path..."
fd -a "models.ts" || true
rg -n "src/core/models.ts|refactron/core/models.py" docs/docs-npm/api/models.mdx refactron/core/models.py || true

echo
echo "If src/core/models.ts is absent and refactron/core/models.py exists, docs path is incorrect for this repository."

Repository: Refactron-ai/Refactron_lib

Length of output: 528


🏁 Script executed:

# Check repository root structure
git ls-files | head -30

# Look for src/ directory
fd -type d "src" --max-depth 2

# Check for any TypeScript files in the repo
fd -type f "\.ts$" | head -20

# Verify Python structure
fd -type d "refactron" --max-depth 1

Repository: Refactron-ai/Refactron_lib

Length of output: 1351


🏁 Script executed:

# Check the actual models.py file to understand the structure
cat -n refactron/core/models.py | head -50

Repository: Refactron-ai/Refactron_lib

Length of output: 1646


Documentation path references non-existent TypeScript file.

Lines 104 and 110 direct readers to src/core/models.ts, but this repository contains Python source code with model definitions in refactron/core/models.py. The src/ directory does not exist. Either update the reference to point to refactron/core/models.py or clarify if this documentation targets a separate JavaScript/TypeScript package.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/docs-npm/api/models.mdx` around lines 104 - 110, The docs reference the
non-existent TypeScript file src/core/models.ts; update the link and text to
point to the actual Python source refactron/core/models.py (or explicitly state
this doc targets a separate JS/TS package if that was intended) and ensure the
types mentioned (PipelineSession, FixQueueItem, FixStatus) are referenced to
their Python definitions or a note is added clarifying language mismatch.

Comment on lines +40 to +42
- Authenticated session (unless your deployment waives auth).
- Supported language detected for the project. See [Languages](/docs-npm/languages/python).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Language prerequisite link is too narrow.

The text says “supported language” but links only to Python. Consider linking to a neutral languages index or both Python and TypeScript pages to avoid misrouting Node users.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/docs-npm/cli/analyze.mdx` around lines 40 - 42, The "Supported language
detected" link currently points only to /docs-npm/languages/python which is too
narrow; update the link target in the docs text "Supported language detected for
the project. See [Languages](/docs-npm/languages/python)." to point to a neutral
languages index (e.g., /docs-npm/languages) or include links to both relevant
pages (e.g., Python and TypeScript) so Node users aren't misrouted; edit the
link target text in docs/docs-npm/cli/analyze.mdx accordingly.

Comment on lines +28 to +39
| Key | Action |
|-----|--------|
| `↑` / `↓` or `j` / `k` | Move selection |
| `d` | Preview diff (dry-run; no write) |
| `Esc` | Dismiss diff overlay |
| `a` | Fix selected issue |
| `A` | Fix all fixable issues |
| `v` | Verify fixed files |
| `/` | Filter issues |
| `g` / `G` | Jump to first / last issue |
| `q` | Quit browser, return to REPL |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Keybinding docs may be incomplete vs implemented navigation model.

This table omits the severity drill-in/navigation pattern (1-4, n/p/b/q) described for the interactive issue viewer. If implementation still follows that model, users will get stuck with the current docs.

Based on learnings: refactron analyze command must show interactive issue viewer (TTY) with severity-grouped navigation using [1-4] to drill in and [n/p/b/q] to navigate, with non-interactive fallback for CI/CD.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/docs-npm/cli/issue-browser.mdx` around lines 28 - 39, The docs table for
the issue browser is missing the severity drill-in and navigation keybindings
used by the interactive viewer; update the CLI docs page (issue-browser.mdx) to
include the keys `1`-`4` for drilling into severity groups and `n`/`p`/`b`/`q`
for next/previous/back/quit navigation, and add a short note that `refactron
analyze` launches the TTY interactive issue viewer with severity-grouped
navigation and falls back to non-interactive output for CI/CD; reference the
interactive issue viewer/keybinding descriptions in the same table and adjacent
paragraph so readers see the mapping next to existing entries like `↑`/`↓`, `d`,
`a`, `A`, `v`, `/`, `g`/`G`, and `q`.

Comment on lines +8 to +9
The Verification Engine is the safety gate between an auto-fix transform and a disk write. It runs a set of checks proportional to the blast radius of the change. A trivial fix in an isolated file only needs a syntax check. A change to a widely-imported core module runs the full test suite.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Blast-level check selection is documented incorrectly.

Line 8 and Lines 63–72 state checks are selected by blast radius, and Line 59 says test gate runs only for high/critical. In current implementation, VerificationEngine always initializes all three checks and executes them sequentially (short-circuiting only on failure), with no blast-level-based skip logic (refactron/verification/engine.py, Lines 30–47 and 48–96).

Suggested doc correction
-The Verification Engine is the safety gate between an auto-fix transform and a disk write. It runs a set of checks proportional to the blast radius of the change. A trivial fix in an isolated file only needs a syntax check. A change to a widely-imported core module runs the full test suite.
+The Verification Engine is the safety gate between an auto-fix transform and a disk write. It runs checks in a fixed sequence and short-circuits on first failure.

-This is the most expensive check and only runs for `high` and `critical` blast radius issues.
+This is the most expensive check and runs after syntax/import checks if earlier checks pass.

-## Check Selection by Blast Level
+## Check Execution Order

-| Blast Level | Syntax | Imports | Test Suite |
-|-------------|--------|---------|------------|
-| `trivial` | ✓ | — | — |
-| `low` | ✓ | — | — |
-| `medium` | ✓ | ✓ | — |
-| `high` | ✓ | ✓ | ✓ |
-| `critical` | ✓ | ✓ | ✓ (120s) |
+| Order | Check |
+|------:|-------|
+| 1 | Syntax |
+| 2 | Imports |
+| 3 | Test gate (if prior checks pass) |

Also applies to: 59-72

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/docs-npm/concepts/verification.mdx` around lines 8 - 9, The doc
incorrectly states checks are selected by blast radius; update the "Verification
Engine" documentation to state that VerificationEngine always initializes and
runs all three checks (syntax, medium, test gate) sequentially, short-circuiting
on the first failure, rather than skipping checks by blast level; specifically
replace any wording that says checks are chosen by blast radius or that the test
gate runs only for high/critical with a clear description of the current
implementation (VerificationEngine initializes all checks and executes them in
order), and optionally add a note that blast-level-based skipping is a
planned/possible enhancement if desired.

Comment on lines +8 to +49
Create `refactron.yaml` in your project root. All fields are optional — Refactron ships with sensible defaults and deep-merges your overrides.

```yaml
# refactron.yaml
version: 1

analyzers:
complexity:
enabled: true
threshold: 10 # cyclomatic complexity limit

security:
enabled: true

code_smell:
enabled: true
max_method_lines: 50 # lines per function/method limit

dead_code:
enabled: true

type_hints:
enabled: true

dependencies:
enabled: true

performance:
enabled: true

verification:
timeout_seconds: 45 # standard check timeout
critical_timeout_seconds: 120 # timeout for critical blast radius checks

autofix:
dry_run: false # set true to never write files
require_verification: true # block fixes that fail verification

output:
format: terminal # terminal | json | sarif
fail_on: null # critical | high | medium | low | null
```
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Documented YAML schema does not match the currently implemented config loader.

The examples/documentation describe nested keys (analyzers.*, verification.*, autofix.*, output.*), but refactron/core/config.py currently accepts flat RefactronConfig fields and constructs via cls(**config_dict). Unknown keys will trigger ConfigError (via TypeError) in from_file (refactron/core/config.py:153-177). As written, users copying this page will provide invalid config and fail at load time.

💡 Proposed direction for a corrected top-level example (aligned to current loader shape)
- version: 1
- analyzers:
-   complexity:
-     enabled: true
-     threshold: 10
- verification:
-   timeout_seconds: 45
- autofix:
-   dry_run: false
- output:
-   format: terminal
+ version: "1"
+ enabled_analyzers:
+   - complexity
+   - code_smells
+   - security
+   - dependency
+   - dead_code
+   - type_hints
+   - performance
+ max_function_complexity: 10
+ max_function_length: 50
+ report_format: text
+ require_preview: true
+ backup_enabled: true

Also applies to: 55-257

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/docs-npm/configuration.mdx` around lines 8 - 49, The docs show nested
config sections (analyzers.*, verification.*, autofix.*, output.*) but the
loader expects flat fields passed into RefactronConfig via
RefactronConfig.from_file (refactron/core/config.py), causing
TypeError/ConfigError; fix by updating this example YAML to the flat top-level
shape that RefactronConfig expects (use the exact field names from the
RefactronConfig dataclass) or alternatively modify RefactronConfig.from_file to
deep-merge and normalize nested sections into the flat dict before calling
cls(**config_dict); reference RefactronConfig and from_file to locate the code
to change.

## Prerequisites

- **Node.js 18+**
- **Git** (optional but recommended — enables temporal analysis and blast radius)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Prerequisite note overstates Git’s role for blast radius.

Line 9 says Git enables temporal analysis and blast radius. Blast radius is described elsewhere as structural analysis (imports/calls/tests), while Git history is for temporal signals. Please remove “blast radius” from this prerequisite note to avoid conflicting guidance.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/docs-npm/quickstart.mdx` at line 9, Update the prerequisite sentence in
quickstart.mdx to stop claiming Git enables "blast radius": edit the line that
currently reads "**Git** (optional but recommended — enables temporal analysis
and blast radius)" to remove "and blast radius" so it only states that Git
enables temporal analysis; keep the rest of the phrasing intact to avoid
conflicting guidance about structural (blast radius) analysis being separate.

@omsherikar omsherikar merged commit a9659f5 into main Apr 4, 2026
23 of 25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size: x-large

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants